<HTML>
<TITLE>module my25_turb_mod</TITLE>
<BODY BGCOLOR="#AABBCC" TEXT="#332211" >

<DIV ALIGN="CENTER"> <FONT SIZE=1>
<A HREF="#INTERFACE">PUBLIC INTERFACE</A> / 
<A HREF="#DATA_TYPES">DATA</A> / 
<A HREF="#ROUTINES">ROUTINES</A> / 
<A HREF="#NAMELIST">NAMELIST</A> / 
<A HREF="#CHANGES">CHANGES</A> / 
<A HREF="#ERRORS">ERRORS</A> / 
<A HREF="#REFERENCES">REFERENCES</A> / 
<A HREF="#NOTES">NOTES</A> 
</FONT>
<BR><BR></DIV><HR>


<H2>module my25_turb_mod</H2>
<A NAME="HEADER">
<PRE>
     <B>Contact:</B>   Joe Sirutis, Bruce Wyman
     <B>Reviewers:</B>

     <B><A HREF=".doc.log#my25_turb.f90">Tags/Status</A></B>
</PRE>
</A><!-- END HEADER -->
<!--------------------------------------------------------------------->
<A NAME="OVERVIEW">
<HR>
<H4>OVERVIEW</H4>
<!-- BEGIN OVERVIEW -->
<PRE>

     Mellor/Yamada level 2.5 turbulent closure parameterization.

     This module provides mixing coefficients for wind, temperature
     and moisture that are used in the vertical diffusion code. 

</PRE>
</A><!-- END OVERVIEW -->
<!--------------------------------------------------------------------->
<A NAME="DESCRIPTION">
<!-- BEGIN DESCRIPTION -->
<PRE>
     Given potential temperature and wind profiles at the model's 
     pressure levels, this module returns mixing coefficients for
     wind, temperature and moisture based on the Mellor/Yamada 
     level 2.5 turbulent closure parameterization. These coefficients
     are then used in the vertical diffusion code.

     The level 2.5 scheme has a prognostic equation for turbulent
     kinetic energy, and a diagnostic relationship for temperature
     variance. The prognostication of the turbulent kinetic energy,
     with the exception of the advection and horizontal diffusion 
     terms, is also done in this module. 

     This module also handles the initialization of the turbulent
     kinetic energy, along with the input/output of a restart file
     for the turbulent kinetic energy.     

</PRE>
</A><!-- END DESCRIPTION -->
<!--------------------------------------------------------------------->
<A NAME="MODULES_USED">
<HR>
<H4>OTHER MODULES USED</H4>
<!-- BEGIN MODULES_USED -->
<PRE>

          constants_mod
        tridiagonal_mod
          utilities_mod
      monin_obukhov_mod

</PRE>
</A><!-- END MODULES_USED -->
<!--------------------------------------------------------------------->
<A NAME="INTERFACE">
<HR>
<H4>PUBLIC INTERFACE</H4>
<!-- BEGIN INTERFACE -->
<PRE>

use my25_turb_mod [,only: my25_turb_init, my25_turb, tke_surf, my25_turb_end]

my25_turb_init  - Called once to initialize my25_turb. Also reads namelist,
                  and restart data for turbulent kinetic energy.
                  Must be called before my25_turb.

my25_turb       - Called every time step. Computes mixing coefficients
                  for momentum, heat, and moisture. Also updates turbulent
                  kinetic energy.

tke_surf        - Prescribes lower boundary condition for 
                  turbulent kinetic energy

my25_turb_end  - Called at the end of the model run to write restart
                 data for turbulent kinetic energy.

Notes:
 1) A namelist interface controls runtime options. 
 2) A restart file for TKE is generated by this module. 

</PRE>
</A><!-- END INTERFACE -->
<!--------------------------------------------------------------------->
<A NAME="DATA_TYPES">
<HR>
<H4>PUBLIC DATA</H4>
<!-- BEGIN DATA_TYPES -->
<PRE>

  real, public, allocatable, dimension(:,:,:) :: TKE

  TKE - global turbulent kinetic energy at model half levels in m^2/sec^2
        If there are "kx" model levels then TKE will have
        "kx+1" half levels.

</PRE>
</A><!-- END DATA_TYPES -->
<!--------------------------------------------------------------------->
<A NAME="ROUTINES">
<HR>
<H4>PUBLIC ROUTINES</H4>
<!-- BEGIN ROUTINES -->
<PRE>

call my25_turb_init (ix, jx, kx)

input

    ix, jx    number of horizontal grid points in the global
              fields along the x and y axis, respectively.
              [integer]

    kx        number of vertical points in a column of the atmosphere
              [integer]

---------------------------------------------------------------------

call my25_turb( delt, fracland, phalf, pfull, theta, &   
                um,   vm,       zhalf, zfull, z0,    &
                TKE,  el0,      el,    akm,   akh,   &
                mask, kbot)

input

    delt       Model time step in seconds
               [real]

    fracland   Fractional amount of land beneath a grid box
               [real, dimension(:,:)]

    phalf      Pressure at half levels in pascals
               [real, dimension(:,:,nlev+1)]

    pfull      Pressure at full levels in pascals
               [real, dimension(:,:,nlev)]

    theta      Potential temperature [deg K] at full model levels
               [real, dimension(:,:,nlev)]

    um         Zonal wind component [m/s] at full model levels,
               [real, dimension(:,:,nlev)]

    vm         Meridional wind component [m/s] at full model levels,
               [real, dimension(:,:,nlev)]

    zhalf      Height at half levels in meters
               [real, dimension(:,:,nlev+1)]

    zfull      Height at full levels in meters
               [real, dimension(:,:,nlev)]

    z0         Surface roughness length in meters
               [real, dimension(:,:)]

input/output

    TKE        Turbulent kinetic energy in m^2/sec^2.
               [real, dimension(:,:,nlev+1)]

output

    el0        Characteristic length scale in meters.
               [real, dimension(:,:)]

    el         Master length scale in meters.
               [real, dimension(:,:,nlev+1)]

    akm        Mixing coefficient for momentum in m^2/sec.
               [real, dimension(:,:,nlev)]

    akh        Mixing coefficient for heat and moisture in m^2/sec.
               [real, dimension(:,:,nlev)]


input (optional) 

    - for use with the step-mountain (eta) vertical coordinate

    mask      Mask (1. or 0.) for grid boxes above or below the ground.
              [real, dimension(:,:,nlev)]

    kbot      Index of the lowest model level
              [integer, dimension(:,:)]

    - for use in diagnosing PBL depth            

    ustar     Friction velocity at the surface (meters/sec)
              [real, dimension(:,:)]

    bstar     Buoyancy scale at the surface (meters/sec**2.)
              [real, dimension(:,:)] 

output (optional)

    h         pbl depth (meters)
              [real, dimension(:,:)]

---------------------------------------------------------------------

 call tke_surf ( u_star, TKE, kbot )

input

    u_star    Surface friction velocity (m/s)
              [real, dimension(:,:)]

input/output

    TKE        Turbulent kinetic energy, in m^2/sec^2.
               [real, dimension(:,:,nlev+1)]

input (optional) - for use with the step-mountain (eta) vertical coordinate

    kbot      Index of the lowest model level
              [integer, dimension(:,:)]

---------------------------------------------------------------------

  call my25_turb_end()

    There are no arguments to this routine.

</PRE>
</A><!-- END ROUTINES -->
<!--------------------------------------------------------------------->
<A NAME="NAMELIST">
<HR>
<H4>NAMELIST</H4>
<!-- BEGIN NAMELIST -->
<PRE>

<b>&my25_turb_nml</b>

   TKEmax        Max value for TKE
                 [real, default: TKEmax = 5.0 m^2/sec^2]

   TKEmin        Min value for TKE
                 [real, default: TKEmin = 0.0 m^2/sec^2]

   akmax         Max value for akm & akh
                 [real, default: akmax = 1.0e4 m^2/sec]

   akmin_land    Min value for akm & akh over land points
                 (Applied to the lowest nk_lim levels)
                 [real, default: akmin_land = 5.0 m^2/sec]

   akmin_sea     Min value for akm & akh over all ocean points
                 (Applied to the lowest nk_lim levels)
                 [real, default: akmin_sea = 0.0 m^2/sec]

   nk_lim        Lower bound on akm & akh applied at lowest nk_lim levels
                 [integer, default: nk_lim = 2 ]

   init_iters    Number of iterations to be used in initializing TKE.
                 Only used if the input restart data does not exist.
                 [integer, default: init_iters = 20 ]

   el0max        Max value for el0
                 [real, default: el0max = 1.0e6 meters]

   el0min        Min value for el0
                 [real, default: el0min = 0.0 meters]

   alpha_land    Constant used in computing el0 ( land value )
                 [real, default: alpha_land = 0.10 ]

   alpha_sea     Constant used in computing el0 ( sea value )
                 [real, default: alpha_land = 0.10 ]

   do_thv_stab   If false, buoyancy computed using constant
                 reference potential temperature.
                 [logical, default: do_thv_stab = .true.]

   use_old_cons  If true,  use original MY constants
                 If false, use revised values
                 [logical, default: use_old_cons = .false.]

   kcrit         Mixing coefficient threshold used to diagnose PBL top.
                 PBL top is set the interpolated height where the mean
                 of the momentum and tracer diffusion coefficient first
                 falls beneath kcrit.
                 [real, default: kcrit = 0.01 m2/sec] 


Notes:
  
  * Diagnostic output from Mellor Yamada 2.5 is controlled by the
    namelist to vert_turb_driver module.

</PRE>
</A><!-- END NAMELIST -->
<!--------------------------------------------------------------------->
<A NAME="DATA_SETS">
<HR>
<H4>DATA SETS</H4>
<!-- BEGIN DATA_SETS -->
<PRE>

     This module automatically writes restart data to file
     "RESTART/my25_turb.res". This file has one record which
     contains the global turbulent kinetic energy field (see the
     section for PUBLIC DATA).

     The input restart data is read from file "INPUT/my25_turb.res".
     If this restart file does not exist, the module will initialize
     TKE by setting TKE = TKEmin and iterating with the same input
     data "init_iters" times.  init_iters is a namelist variable.

</PRE>
</A><!-- END DATA_SETS -->
<!--------------------------------------------------------------------->
<A NAME="CHANGES">
<HR>
<H4>CHANGE HISTORY</H4>
<!-- BEGIN CHANGES -->
<PRE>
<B><A HREF=".doc.log#my25_turb.f90">Revision history</A></B>

<b>changes</b> (8/31/99)

    A diagnostic subroutine was added which diagnoses the pbl depth
    as the height to which the interpolated mean diffusivity coefficients
    (mean of akm and akh) falls beneath a specified value, kcrit (a
    new namelist variable which is defaulted to 0.01 m^2/sec).

</PRE>
</A><!-- END CHANGES -->
<!--------------------------------------------------------------------->
<A NAME="ERRORS">
<HR>
<H4>ERROR MESSAGES</H4>
<!-- BEGIN ERRORS -->
<PRE>

<b>Fatal Errors in MY25_TURB</b>

    <b>MY25_TURB_INIT has not been called</b>
        The initialization routine for this module must be called
        before calling routine MY25_TURB.

    <b>divid by zero, x1 <= 0.0</b>
        This error should never occur.
        If it occurs, contact the developer.

    <b>cannot request pbl depth if ustar and bstar are not also supplied</b>
        If you request (as an optional argument to my25_turb)
        the pbl depth, h, the calculation also needs the optional 
        arguments ustar, and bstar.

</PRE>
</A><!-- END ERRORS -->
<!--------------------------------------------------------------------->
<A NAME="REFERENCES">
<HR>
<H4>REFERENCES</H4>
<!-- BEGIN REFERENCES -->
<PRE>

     Mellor, G.L. and T. Yamada, 1974: A hierarchy of turbulent
          closure models for planetary boundary layers. J. Atmos.
          Sci., 31, 1791-1806.

     Mellor, G.L. and T. Yamada, 1982: Development of a turbulent
          closure model for geophysical fluid problems. Rev. Geophys.
          Space Phys. 20, 851-875.

</PRE>
</A><!-- END REFERENCES -->
<!--------------------------------------------------------------------->
<A NAME="BUGS">
<HR>
<H4>KNOWN BUGS</H4>
<!-- BEGIN BUGS -->
<PRE>

     There are no known bugs.

</PRE>
</A><!-- END BUGS -->
<!--------------------------------------------------------------------->
<A NAME="NOTES">
<HR>
<H4>NOTES</H4>
<!-- BEGIN NOTES -->
<PRE>

    None.

</PRE>
</A><!-- END NOTES -->
<!--------------------------------------------------------------------->
<A NAME="PLANS">
<HR>
<H4>FUTURE PLANS</H4>
<!-- BEGIN PLANS -->
<PRE>

    None.

</PRE>
</A><!-- END PLANS -->
<!--------------------------------------------------------------------->

<HR>
</BODY>
</HTML>
